<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Chapter 19 MySQL Shell User Guide</title>
<link rel="stylesheet" href="mvl.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets + chunker.py v1.9.2" />
<link rel="start" href="index.html" title="{book-title}" />
<link rel="up" href="" title="" />
<link rel="prev" href="group-replication.html" title="Chapter 18 Group Replication" />
<link rel="next" href="document-store.html" title="Chapter 20 Using MySQL as a Document Store" />
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 19 MySQL Shell User Guide</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="group-replication.html">Prev</a> </td>
<th width="60%" align="center"></th>
<td width="20%" align="right"> <a accesskey="n" href="document-store.html">Next</a></td>
</tr>
</table>
<hr>
</div>
<div lang="en" class="chapter">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a name="mysql-shell"></a>Chapter 19 MySQL Shell User Guide</h1>

</div>

</div>

</div>
<div class="toc">
<p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-features">19.1 MySQL Shell Features</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-getting-started">19.2 Getting Started with MySQL Shell</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-shell.html#mysql-shell-connections">19.2.1 MySQL Shell Connections</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-sessions">19.2.2 MySQL Shell Sessions</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-global-variables">19.2.3 MySQL Shell Global Variables</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-working-with-history">19.2.4 MySQL Shell Code History</a></span></dt></dl></dd><dt><span class="section"><a href="mysql-shell.html#mysql-shell-code-execution">19.3 MySQL Shell Code Execution</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-shell.html#mysql-shell-interactive-code-execution">19.3.1 Interactive Code Execution</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-autocompletion">19.3.2 Code Autocompletion</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-batch-code-execution">19.3.3 Batch Code Execution</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-output-formats">19.3.4 Output Formats</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-active-language">19.3.5 Active Language</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-batch-mode-interactive">19.3.6 Batch Mode Made Interactive</a></span></dt></dl></dd><dt><span class="section"><a href="mysql-shell.html#mysql-shell-configuring">19.4 Configuring MySQL Shell</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-shell.html#mysql-shell-commands">19.4.1 MySQL Shell Commands</a></span></dt></dl></dd><dt><span class="section"><a href="mysql-shell.html#mysql-shell-utilities">19.5 MySQL Shell Utilities</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-application-log">19.6 MySQL Shell Application Log</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-shell.html#mysql-shell-application-log-introduction">19.6.1 Application Log</a></span></dt></dl></dd><dt><span class="section"><a href="mysql-shell.html#mysql-shell-customizing">19.7 Customizing MySQL Shell</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-shell.html#mysql-shell-creating-startup-scripts">19.7.1 Working With Start-Up Scripts</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-adding-module-search-paths">19.7.2 Adding Module Search Paths</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-prompt-themes">19.7.3 Customizing the Prompt</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-configuring-options">19.7.4 Configuring MySQL Shell</a></span></dt></dl></dd></dl>
</div>
<p>
    This section provides user documentation for MySQL Shell, an
    advanced client and code editor for MySQL Server. In addition to the
    provided SQL functionality, similar to <a class="link" href="programs.html#mysql" title="4.5.1 mysql — The MySQL Command-Line Tool"><span class="command"><strong>mysql</strong></span></a>,
    MySQL Shell provides scripting capabilities for JavaScript and
    Python and includes APIs for working with MySQL. X DevAPI
    enables you to work with both relational and document data, see
    <a class="xref" href="document-store.html" title="Chapter 20 Using MySQL as a Document Store">Chapter 20, <i>Using MySQL as a Document Store</i></a>. AdminAPI enables you to
    work with InnoDB cluster, see
    <a class="xref" href="mysql-innodb-cluster-userguide.html" title="Chapter 21 InnoDB Cluster">Chapter 21, <i>InnoDB Cluster</i></a>.
  </p><p>
    This section describes core features of MySQL Shell.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-features"></a>19.1 MySQL Shell Features</h2>
</div>
</div>
</div>
<p>
    The following features are available in MySQL Shell.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h3 class="title"><a name="idm139899489912000"></a>Interactive Code Execution</h3>
</div>
</div>
</div>
<p>
      MySQL Shell provides an interactive code execution mode, where
      you type code at the MySQL Shell prompt and each entered
      statement is processed, with the result of the processing printed
      onscreen. Unicode text input is supported if the terminal in use
      supports it. Color terminals are supported.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489910448"></a>Supported Languages</h3>

</div>

</div>

</div>
<p>
      MySQL Shell processes code in the following languages:
      JavaScript, Python and SQL. Any entered code is processed as one
      of these languages, based on the language that is currently
      active. There are also specific MySQL Shell commands, prefixed
      with <code class="literal">\</code>, which enable you to configure
      MySQL Shell regardless of the currently selected language. For
      more information see <a class="xref" href="mysql-shell.html#mysql-shell-commands" title="19.4.1 MySQL Shell Commands">Section 19.4.1, “MySQL Shell Commands”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489907328"></a>Batch Code Execution</h3>

</div>

</div>

</div>
<p>
      In addition to the interactive execution of code, MySQL Shell
      can also take code from different sources and process it. This
      method of processing code in a non-interactive way is called
      <span class="emphasis"><em>Batch Execution</em></span>.
    </p><p>
      As batch execution mode is intended for script processing of a
      single language, it is limited to having minimal non-formatted
      output and disabling the execution of commands. To avoid these
      limitations, use the <a class="link" href="programs.html#option_mysqlsh_interactive"><code class="option">--interactive</code></a>
      command-line option, which tells MySQL Shell to execute the
      input as if it were an interactive session. In this mode the input
      is processed <span class="emphasis"><em>line by line</em></span> just as if each
      line were typed in an interactive session. For more information
      see <a class="xref" href="mysql-shell.html#mysql-shell-batch-mode-interactive" title="19.3.6 Batch Mode Made Interactive">Section 19.3.6, “Batch Mode Made Interactive”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489902352"></a>Output Formats</h3>

</div>

</div>

</div>
<p>
      MySQL Shell provides output in different formats depending on
      how it is used: Tabbed, Table and JSON. For more information see
      <a class="xref" href="mysql-shell.html#mysql-shell-output-formats" title="19.3.4 Output Formats">Section 19.3.4, “Output Formats”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489900128"></a>Multiple-line Support</h3>

</div>

</div>

</div>
<p>
      Multiple-line code can be written using a command, enabling
      MySQL Shell to cache multiple lines and then execute them as a
      single statement. For more information see
      <a class="xref" href="mysql-shell.html#mysql-shell-multiple-line-support" title="19.3.6.1 Multiple-line Support">Section 19.3.6.1, “Multiple-line Support”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489897856"></a>Application Log</h3>

</div>

</div>

</div>
<p>
      MySQL Shell can be configured to log information about the
      execution process. For more information see
      <a class="xref" href="mysql-shell.html#mysql-shell-application-log" title="19.6 MySQL Shell Application Log">Section 19.6, “MySQL Shell Application Log”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489895824"></a>Supported APIs</h3>

</div>

</div>

</div>
<p>
      MySQL Shell includes the following APIs implemented in
      JavaScript and Python which you can use to develop code that
      interacts with MySQL.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          The X DevAPI enables you to work with both relational
          and document data when MySQL Shell is connected to a MySQL
          server using the X Protocol. For more information, see
          <a class="xref" href="document-store.html" title="Chapter 20 Using MySQL as a Document Store">Chapter 20, <i>Using MySQL as a Document Store</i></a>. For documentation on the
          concepts and usage of X DevAPI, see
          <a class="ulink" href="http://dev.mysql.com/doc/x-devapi-userguide/en/" target="_top">X DevAPI User Guide</a>.
        </p></li><li class="listitem"><p>
          The AdminAPI enables you to work with
          InnoDB cluster, which provides an integrated solution for
          high availability and scalability using InnoDB based MySQL
          databases, without requiring advanced MySQL expertise. See
          <a class="xref" href="mysql-innodb-cluster-userguide.html" title="Chapter 21 InnoDB Cluster">Chapter 21, <i>InnoDB Cluster</i></a>.
</p></li></ul>
</div>
<p>
      For specific documentation on the implementation of the APIs see
      <a class="ulink" href="http://dev.mysql.com/doc/dev//mysqlsh-api-javascript/8.0/" target="_top">JavaScript</a>
      and
      <a class="ulink" href="http://dev.mysql.com/doc/dev//mysqlsh-api-python/8.0/" target="_top">Python</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489887840"></a>X Protocol Support</h3>

</div>

</div>

</div>
<p>
      MySQL Shell is designed to provide an integrated command-line
      client for all MySQL products which support X Protocol. The
      development features of MySQL Shell are designed for sessions
      using the X Protocol. MySQL Shell can also connect to
      MySQL Servers that do not support the X Protocol using the
      legacy MySQL Protocol. A minimal set of features from the
      X DevAPI are available for sessions created using the legacy
      MySQL protocol.

      
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h3 class="title"><a name="idm139899489885424"></a>Global Session</h3>

</div>

</div>

</div>
<p>
      Interaction with a MySQL Server is done through a Session object.
      For Python and JavaScript, a Session can be created through the
      <code class="literal">getSession</code> function of the
      <code class="literal">mysqlx</code> module. If a session is created in
      JavaScript mode using any of these methods, it is available only
      in JavaScript mode. The same happens if the session is created in
      Python mode. These sessions cannot be used in SQL mode.
    </p><p>
      For SQL Mode, the concept of Global Session is supported by the
      MySQL Shell. A Global Session is created when the connection
      information is passed to MySQL Shell using command options, or
      by using the <code class="literal">\connect</code> command.
    </p><p>
      The Global Session is used to execute statements in SQL mode and
      the same session is available in both Python or JavaScript modes.
      When a Global Session is created, a variable called
      <code class="literal">session</code> is set in the scripting languages, so
      you can execute code in the different languages by switching the
      active mode.
    </p><p>
      For more information, see <a class="xref" href="mysql-shell.html#mysql-shell-sessions" title="19.2.2 MySQL Shell Sessions">Section 19.2.2, “MySQL Shell Sessions”</a>.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-getting-started"></a>19.2 Getting Started with MySQL Shell</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-connections">19.2.1 MySQL Shell Connections</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-sessions">19.2.2 MySQL Shell Sessions</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-global-variables">19.2.3 MySQL Shell Global Variables</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-working-with-history">19.2.4 MySQL Shell Code History</a></span></dt></dl>
</div>
<p>
    This section describes how to get started with MySQL Shell,
    explaining how to connect to a MySQL server instance, and how to
    choose a session type.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-connections"></a>19.2.1 MySQL Shell Connections</h3>

</div>

</div>

</div>

<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-connection-using-uri">19.2.1.1 Connecting using a URI String</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-connection-using-parameters">19.2.1.2 Connecting using Individual Parameters</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-encrypted-connections">19.2.1.3 Using Encrypted Connections</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-connections-in-javascript-and-python">19.2.1.4 Connections in JavaScript and Python</a></span></dt></dl>
</div>
<p>
      MySQL Shell can connect to MySQL Server using both the
      X Protocol and the classic MySQL protocol. The address of
      the MySQL Server which you want to connect to can be specified
      using individual parameters, such as user, hostname and port, or
      using a Uniform Resource Identifier (URI) type string. The
      following sections describe these connection methods. See
      <a class="xref" href="programs.html#connecting" title="4.2.2 Connecting to the MySQL Server">Section 4.2.2, “Connecting to the MySQL Server”</a> for more background information.
    </p><p>
      You can configure the MySQL server instance that MySQL Shell is
      connected to in the following ways:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          When you start MySQL Shell using the command parameters. See
          <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-parameters" title="19.2.1.2 Connecting using Individual Parameters">Section 19.2.1.2, “Connecting using Individual Parameters”</a>.
        </p></li><li class="listitem"><p>
          When MySQL Shell is running using the
          <code class="literal">\connect</code> command. See
          <a class="xref" href="mysql-shell.html#mysql-shell-commands" title="19.4.1 MySQL Shell Commands">Section 19.4.1, “MySQL Shell Commands”</a>.
        </p></li><li class="listitem"><p>
          When running Python or Java code using the
          <code class="literal">shell.connect('<em class="replaceable"><code>instance</code></em>')</code>
          method. See
          <a class="ulink" href="http://dev.mysql.com/doc/dev//mysqlsh-api-javascript/8.0/" target="_top">JavaScript</a>
          and
          <a class="ulink" href="http://dev.mysql.com/doc/dev//mysqlsh-api-python/8.0/" target="_top">Python</a>.
</p></li></ul>
</div>
<p>
      These methods all support
      <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a>.
</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
        Regardless of the method you choose to connect it is important
        to understand how passwords are handled by MySQL Shell. By
        default connections are assumed to require a password. The
        password is requested at the login prompt. If the user has a
        password-less account, which is insecure and not recommended, or
        if socket peer-credential authentication is in use (for Unix
        socket connections), you must explicitly specify that no
        password is provided and the password prompt is not required. To
        do this, use one of the following methods:

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              If you are connecting using a URI type string, place a
              <code class="literal">:</code> after the <code class="literal">user</code> in
              the URI type string but do not specify a password after
              it.
            </p></li><li class="listitem"><p>
              If you are connecting using individual parameters, either
              specify the <a class="link" href="programs.html#option_mysqlsh_no-password"><code class="option">--no-password</code></a>
              option, or specify the
              <a class="link" href="programs.html#option_mysqlsh_password"><code class="option">--password=</code></a> option with an
              empty value.
</p></li></ul>
</div>
<p>
</p>
</div>
<p>
      If you do not specify parameters for a connection the following
      defaults are used:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          user defaults to the current system user name
        </p></li><li class="listitem"><p>
          host defaults to localhost
        </p></li><li class="listitem"><p>
          port defaults to the X Plugin port 33060 when using an
          X Protocol session, and port 3306 when using a Classic
          session
</p></li></ul>
</div>
<p>
      MySQL Shell connections using X Protocol can use either TCP or
      Unix sockets as of version 8.0.4. Previous versions use only TCP
      for X Protocol connections and using Unix sockets is not
      supported. MySQL Shell connections using MySQL Protocol default
      to using Unix sockets when the following conditions are met:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          A TCP port is not specified
        </p></li><li class="listitem"><p>
          A host name is not specified or it is equal to
          <code class="literal">localhost</code>
        </p></li><li class="listitem"><p>
          A socket is provided with a path to a socket file
        </p></li><li class="listitem"><p>
          A classic session is specified
</p></li></ul>
</div>
<p>
      If a host name is specified but it is not
      <code class="literal">localhost</code>, a TCP connection is established. In
      this case, if a TCP port is not specified the default value of
      3306 is used. If the conditions are met for a socket connection
      but a path to a socket file is not specified then the default
      socket is used. See <a class="xref" href="programs.html#connecting" title="4.2.2 Connecting to the MySQL Server">Section 4.2.2, “Connecting to the MySQL Server”</a>.
    </p><p>
      If the connection to the server is lost, MySQL Shell does not
      attempt to reconnect automatically. You can use the MySQL Shell
      <code class="literal">\reconnect</code> command, which makes MySQL Shell
      try several reconnection attempts for the current global session
      with the previously supplied parameters.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-connection-using-uri"></a>19.2.1.1 Connecting using a URI String</h4>
</div>
</div>
</div>
<p>
        You can configure the MySQL Server which MySQL Shell connects
        to by passing the connection data in URI type string format.
        Such strings can be used with the
        <a class="link" href="programs.html#option_mysqlsh_uri"><code class="option">--uri</code></a> command option, the
        MySQL Shell <code class="literal">\connect</code> command, and the
        <code class="literal">shell.connect()</code> method.
      </p><p>
        The URI type string should use the following format:
      </p><pre class="programlisting">
<em class="replaceable"><code>scheme</code></em>://[<em class="replaceable"><code>user</code></em>[:[<em class="replaceable"><code>password</code></em>]]@]<em class="replaceable"><code>target</code></em>[:<em class="replaceable"><code>port</code></em>][/<em class="replaceable"><code>schema</code></em>][?<em class="replaceable"><code>attribute1=value1&amp;attribute2=value2...</code></em>
</pre>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Important
</div>
<p>
          Percent encoding must be used for reserved characters in the
          elements of the URI type string. For example, if you specify a
          password that includes the <code class="literal">@</code> character, the
          character must be replaced by <code class="literal">%40</code>.

          
</p>
</div>
<p>
        The elements of a URI type string for a MySQL Shell connection
        are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <em class="replaceable"><code>scheme</code></em>: this element is required
            and specifies the connection protocol to use, currently
            either <code class="literal">mysql</code> for classic connection
            protocol and <code class="literal">mysqlx</code> for X Protocol.
          </p></li><li class="listitem"><p>
            <em class="replaceable"><code>user</code></em>: this element is optional
            and specifies the MySQL user account to be used for the
            authentication process.
          </p></li><li class="listitem"><p>
            <em class="replaceable"><code>password</code></em>: this element is
            optional and specifies the password to be used for the
            authentication process.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
              Storing the password in the URI type string is insecure
              and not recommended.
</p>
</div>
</li><li class="listitem"><p>
            <em class="replaceable"><code>target</code></em>: this element is required
            and specifies the server instance the connection refers to.
            Can be either TCP connection information, a Unix socket path
            or a Windows named-pipe. If not specified,
            <span class="emphasis"><em>localhost</em></span> is used by default.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                TCP connection information can be either a host name, an
                IPv4 address, or an IPv6 address. Can include an
                optional port number in the format
                <code class="literal">host:port</code>, where
                <em class="replaceable"><code>port</code></em> specifies a network port
                which the target MySQL server is listening on for
                connections. If not specified, 33060 is used by default
                for X Protocol connections, and 3306 is the
                default for classic MySQL protocol connections.
              </p></li><li class="listitem"><p>
                Unix socket and Windows named-pipe values are local file
                paths. There are two ways to specify such paths, using
                percent encoding or surrounding the path with
                parentheses, removing the need to percent encode
                characters such as the common directory separator
                <code class="literal">/</code>. For example, to connect as
                <code class="literal">root@localhost</code> using the Unix socket
                <code class="filename">/tmp/mysqld.sock</code> either specify the
                path using parenthesis as
                <code class="literal">root@localhost?socket=(/tmp/mysqld.sock)</code>
                or using percent encoding as
                <code class="literal">root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F</code>.
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <em class="replaceable"><code>schema</code></em>: this element is optional
            and specifies the database to be set as default when the
            connection is established.
          </p></li><li class="listitem"><p>
            <em class="replaceable"><code>?attribute=value</code></em>: this element is
            optional and specifies a data dictionary that contains

            

            options.
</p></li></ul>
</div>
<p>
        If no password is specified using the URI type string, which is
        recommended, then the password is prompted for. The following
        examples show how to specify URI type strings with the user name
        <em class="replaceable"><code>user</code></em>, in each case the password is
        prompted for:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            An X Protocol connection to a local server instance
            listening at port 33065.
          </p><pre class="programlisting">
mysqlx://user@localhost:33065
</pre></li><li class="listitem"><p>
            A classic MySQL protocol X Protocol connection to a
            local server instance listening at port 3333.
          </p><pre class="programlisting">
mysql://user@localhost:3333
</pre></li><li class="listitem"><p>
            An X Protocol connection to a remote server instance,
            using a host name, an IPv4 address and an IPv6 address.
          </p><pre class="programlisting">
mysqlx://user@server.example.com/
mysqlx://user@198.51.100.14:123
mysqlx://user@[2001:db8:85a3:8d3:1319:8a2e:370:7348]
		</pre></li><li class="listitem"><p>
            An optional path can be specified, which represents a
            database schema.

            
          </p><pre class="programlisting">
mysqlx://user@198.51.100.1/world%5Fx
mysqlx://user@198.51.100.2:33060/world
		</pre></li><li class="listitem"><p>
            An optional query can be specified, consisting of values in
            the form of a <code class="literal">key=value</code> pair or as a
            single <code class="literal">key</code>. The <code class="literal">,</code>
            character is used as a separator for values, a combination
            of multiple pairs and keys can be specified. Values can be
            of type list, list values are ordered by appearance. Strings
            must be percent encoded.

            
          </p><pre class="programlisting">
ssluser@127.0.0.1?ssl-ca%3D%2Froot%2Fclientcert%2Fca-cert.pem%26ssl-cert%3D%2Fro\
ot%2Fclientcert%2Fclient-cert.pem%26ssl-key%3D%2Froot%2Fclientcert%2Fclient-key
.pem
</pre></li></ul>
</div>
<p>
        Although using a password-less account is insecure and not
        recommended, you can specify a user without a password using a
        <em class="replaceable"><code>:</code></em> after the user name, for example:
      </p><p>
        By default, MySQL Shell assumes that connections require a
        password. The password is requested at the login prompt. If the
        user has a password-less account, which is insecure and not
        recommended, or if socket peer-credential authentication is in
        use (for Unix socket connections), you must explicitly specify
        that no password is provided and the password prompt is not
        required. To do this, place a <code class="literal">:</code> after the
        <code class="literal">user</code> in the URI type string but do not
        specify a password after it. For example:
      </p><pre class="programlisting">
mysqlx://user:@localhost
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-connection-using-parameters"></a>19.2.1.2 Connecting using Individual Parameters</h4>

</div>

</div>

</div>
<p>
        In addition to specifying connection parameters using a URI type
        string, it is also possible to define the connection data when
        starting MySQL Shell using separate command parameters for
        each value. For a full reference of MySQL Shell command
        options see <a class="xref" href="programs.html#mysqlsh" title="4.5.7 mysqlsh — The MySQL Shell">Section 4.5.7, “<span class="command"><strong>mysqlsh</strong></span> — The MySQL Shell”</a>.
      </p><p>
        Use the following connection related parameters:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_dbuser"><code class="option">--dbuser</code></a>
            (<code class="option">-u</code>) <em class="replaceable"><code>value</code></em>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_dbpassword"><code class="option">--dbpassword</code></a>
            (<code class="option">-p</code>) <em class="replaceable"><code>value</code></em>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_host"><code class="option">--host</code></a> (<code class="option">-h</code>)
            <em class="replaceable"><code>value</code></em>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_port"><code class="option">--port</code></a> (<code class="option">-P</code>)
            <em class="replaceable"><code>value</code></em>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_schema"><code class="option">--schema</code></a>
            (<code class="option">-D</code>) <em class="replaceable"><code>value</code></em>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_no-password"><code class="option">--no-password</code></a>, or
            <a class="link" href="programs.html#option_mysqlsh_password"><code class="option">--password=</code></a> with an empty
            value, if the user is connecting without a password
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_socket"><code class="option">--socket</code></a>
            (<code class="option">-S</code>)
</p></li></ul>
</div>
<p>
        The first 5 parameters match the elements used in the URI type
        string format described at
        <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a>.
      </p><p>
        By default, MySQL Shell assumes that connections require a
        password. The password is requested at the login prompt. If the
        user has a password-less account, which is insecure and not
        recommended, or if socket peer-credential authentication is in
        use (for Unix socket connections), you must explicitly specify
        that no password is provided and the password prompt is not
        required. To do this, either specify the
        <a class="link" href="programs.html#option_mysqlsh_no-password"><code class="option">--no-password</code></a> option, or specify
        the <a class="link" href="programs.html#option_mysqlsh_password"><code class="option">--password=</code></a> option with an
        empty value.
      </p><p>
        For consistency, the following aliases are supported for some
        parameters:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_user"><code class="option">--user</code></a> is equivalent to
            <a class="link" href="programs.html#option_mysqlsh_dbuser"><code class="option">--dbuser</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_password"><code class="option">--password</code></a> specified with a
            value is equivalent to
            <a class="link" href="programs.html#option_mysqlsh_dbpassword"><code class="option">--dbpassword</code></a>
          </p></li><li class="listitem"><p>
            <a class="link" href="programs.html#option_mysqlsh_database"><code class="option">--database</code></a> is equivalent to
            <a class="link" href="programs.html#option_mysqlsh_schema"><code class="option">--schema</code></a>
</p></li></ul>
</div>
<p>
        When parameters are specified in multiple ways, for example
        using both the <a class="link" href="programs.html#option_mysqlsh_uri"><code class="option">--uri</code></a> option and
        specifying individual parameters such as
        <a class="link" href="programs.html#option_mysqlsh_user"><code class="option">--user</code></a>, the following rules
        apply:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            If an argument is specified more than once the value of the
            last appearance is used.
          </p></li><li class="listitem"><p>
            If both individual connection arguments and
            <a class="link" href="programs.html#option_mysqlsh_uri"><code class="option">--uri</code></a> are specified, the
            value of <a class="link" href="programs.html#option_mysqlsh_uri"><code class="option">--uri</code></a> is taken as
            the base and the values of the individual arguments override
            the specific component from the base URI.
          </p><p>
            For example to override <em class="replaceable"><code>user</code></em> from
            the URI:
          </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --uri <em class="replaceable"><code>user</code></em>@localhost:33065 --user <em class="replaceable"><code>otheruser</code></em></code></strong>
</pre></li></ul>
</div>
<p>
        The following examples show how to use command parameters to
        specify connections. Attempt to establish an X Protocol
        connection with a specified user at port 33065.
      </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --mysqxl -u <em class="replaceable"><code>user</code></em> -h localhost -P 33065</code></strong>
</pre><p>
        Attempt to establish a classic MySQL protocol connection with a
        specified user.
      </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --mysql -u <em class="replaceable"><code>user</code></em> -h localhost</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-encrypted-connections"></a>19.2.1.3 Using Encrypted Connections</h4>

</div>

</div>

</div>
<p>
        Using encrypted connections is possible when connecting to a TLS
        (sometimes referred to as SSL) enabled MySQL server. Much of the
        configuration of MySQL Shell is based on the options used by
        MySQL server, see <a class="xref" href="security.html#encrypted-connections" title="6.4 Using Encrypted Connections">Section 6.4, “Using Encrypted Connections”</a> for
        more information.
      </p><p>
        To configure an encrypted connection at startup of
        MySQL Shell, use the following command options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl"><code class="option">--ssl</code></a> : Deprecated, to be
            removed in a future version. This option enables or disables
            encrypted connections.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-mode"><code class="option">--ssl-mode</code></a> : This option
            specifies the security state of the connection to the
            server.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-ca"><code class="option">--ssl-ca=<em class="replaceable"><code>filename</code></em></code></a>:
            The path to a file in PEM format that contains a list of
            trusted SSL Certificate Authorities.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-capath"><code class="option">--ssl-capath=<em class="replaceable"><code>directory</code></em></code></a>:
            The path to a directory that contains trusted SSL
            Certificate Authority certificates in PEM format.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-cert"><code class="option">--ssl-cert=<em class="replaceable"><code>filename</code></em></code></a>:
            The name of the SSL certificate file in PEM format to use
            for establishing an encrypted connection.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-cipher"><code class="option">--ssl-cipher=<em class="replaceable"><code>name</code></em></code></a>:
            The name of the SSL cipher to use for establishing an
            encrypted connection.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-key"><code class="option">--ssl-key=<em class="replaceable"><code>filename</code></em></code></a>:
            The name of the SSL key file in PEM format to use for
            establishing an encrypted connection.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-crl"><code class="option">--ssl-crl=<em class="replaceable"><code>name</code></em></code></a>:
            The path to a file containing certificate revocation lists
            in PEM format.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_ssl-crlpath"><code class="option">--ssl-crlpath=<em class="replaceable"><code>directory</code></em></code></a>:
            The path to a directory that contains files containing
            certificate revocation lists in PEM format.
          </p></li><li class="listitem"><p>
            <a class="link" href="security.html#option_general_tls-version"><code class="option">--tls-version=<em class="replaceable"><code>version</code></em></code></a>:
            The TLS protocols permitted for encrypted connections.
</p></li></ul>
</div>
<p>
        Alternatively, the SSL options can be encoded as part of a URI
        type string as part of the query element. The available SSL
        options are the same as those listed above, but written without
        the preceding hyphens. For example, <code class="literal">ssl-ca</code> is
        the equivalent of <a class="link" href="security.html#option_general_ssl-ca"><code class="option">--ssl-ca</code></a>.
      </p><p>
        Paths specified in a URI type string must be percent encoded,
        for example:
      </p><pre class="programlisting">
ssluser@127.0.0.1?ssl-ca%3D%2Froot%2Fclientcert%2Fca-cert.pem%26ssl-cert%3D%2Fro\
ot%2Fclientcert%2Fclient-cert.pem%26ssl-key%3D%2Froot%2Fclientcert%2Fclient-key
.pem
</pre><p>
        See <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a> for more
        information.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-connections-in-javascript-and-python"></a>19.2.1.4 Connections in JavaScript and Python</h4>

</div>

</div>

</div>
<p>
        When a connection is made using the command options or by using
        any of the MySQL Shell commands, a global session object is
        created. This session is global because once created, it can be
        used in any of the MySQL Shell execution modes.
      </p><p>
        Any global session object is available in JavaScript or Python
        modes because a variable called
        <span class="strong"><strong>session</strong></span> holds a reference to
        it.
      </p><p>
        In addition to the global session object, sessions can be
        established and assigned to a different variable by using the
        functions available in the <code class="literal">mysql</code> and
        <code class="literal">mysqlx</code> JavaScript and Python modules.
      </p><p>
        For example, the following functions are provided by these
        modules:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">mysqlx.getSession(connectionData[,
            password])</code>
          </p><p>
            The returned object can be Session if the object was created
            or retrieved using a Session instance, and ClassicSession if
            the object was created or retrieved using a ClassicSession
            instance.
          </p></li><li class="listitem"><p>
            <code class="literal">mysql.getClassicSession(connectionData[,
            password])</code>
          </p><p>
            The returned object is a ClassicSession which uses the
            traditional MySQL protocol and has a limited development
            API.
</p></li></ul>
</div>
<p>
        <code class="literal">connectionData</code> can be either a URI type
        string as specified at
        <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a> or a
        dictionary containing the connection parameters.
      </p><p>
        Sessions created using either
        <code class="literal">mysql.getClassicSession(connection_data)</code> or
        <code class="literal">mysqlx.getSession(connection_data)</code> use
        <code class="literal">ssl-mode=REQUIRED</code> as the default if no
        <code class="literal">ssl-mode</code> is provided, and neither
        <code class="literal">ssl-ca</code> nor <code class="literal">ssl-capath</code> is
        provided. If no <code class="literal">ssl-mode</code> is provided and any
        of <code class="literal">ssl-ca</code> or <code class="literal">ssl-capath</code> is
        provided, created sessions default to
        <code class="literal">ssl-mode=VERIFY_CA</code>.
      </p><p>
        The following example shows how to create a Session using the
        X Protocol:
      </p><pre class="programlisting">
mysql-js&gt; <strong class="userinput"><code>var mysession1=mysqlx.getSession('root@localhost:33060', '<em class="replaceable"><code>password</code></em>');</code></strong>
mysql-js&gt; <strong class="userinput"><code>session</code></strong>
&lt;Session:root@localhost&gt;
mysql-js&gt;
</pre><p>
        The following example shows how to create a ClassicSession:
      </p><pre class="programlisting">
mysql-js&gt; <strong class="userinput"><code>var mysession2=mysql.getClassicSession('root@localhost:3306', '<em class="replaceable"><code>password</code></em>');</code></strong>
mysql-js&gt; <strong class="userinput"><code>session</code></strong>
&lt;ClassicSession:root@localhost:3306&gt;
mysql-js&gt;
</pre>
<div class="section">

<div class="titlepage">
<div>
<div>
<h5 class="title"><a name="mysql-shell-using-ssl-connection-data"></a>19.2.1.4.1 Using Encrypted Connections in Code</h5>
</div>
</div>
</div>
<p>
          To establish an encrypted connection, set the SSL information
          in the <code class="literal">connectionData</code> dictionary. For
          example:
        </p><pre class="programlisting">
mysql-js&gt; <strong class="userinput"><code>var session=mysqlx.getSession({host: 'localhost',
                                             dbUser: 'root',
                                             dbPassword: '<em class="replaceable"><code>password</code></em>',
                                             ssl_ca: "path_to_ca_file",
                                             ssl_cert: "path_to_cert_file",
                                             ssl_key: "path_to_key_file"});</code></strong>

</pre>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-sessions"></a>19.2.2 MySQL Shell Sessions</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-sessions-introduction">19.2.2.1 MySQL Shell Sessions Explained</a></span></dt></dl>
</div>
<p>
      This section explains the different types of sessions in
      MySQL Shell and how to create and configure them.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-sessions-introduction"></a>19.2.2.1 MySQL Shell Sessions Explained</h4>
</div>
</div>
</div>
<p>
        MySQL Shell is a unified interface to operate MySQL Server
        through scripting languages such as JavaScript or Python. To
        maintain compatibility with previous versions, SQL can also be
        executed in certain modes. A connection to a MySQL server is
        required. In MySQL Shell these connections are handled by a
        <span class="emphasis"><em>Session</em></span> object.
      </p><p>
        The following types of Session object are available:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <span class="emphasis"><em>Session</em></span>: Use this session type for new
            application development to communicate with MySQL server
            instances which have the X Protocol enabled. It offers
            the best integration with MySQL Server, and therefore, it is
            used by default.
          </p></li><li class="listitem"><p>
            <span class="emphasis"><em>ClassicSession</em></span> Use this session type to
            interact with MySQL Servers that do not have the
            X Protocol enabled. The development API available for
            this type of session is very limited. For example, there are
            no CRUD operations, no collection handling, and binding is
            not supported.
</p></li></ul>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-shell-choose-session-type"></a>Choosing a MySQL Shell Session Type</h5>

</div>

</div>

</div>
<p>
          MySQL Shell creates a Session object by default. You can
          either configure the session type using MySQL Shell command
          options, the <code class="literal">scheme</code> element of a URI type
          string, or provide an option to the
          <code class="literal">\connect</code> command. To choose which type of
          session should be created when starting MySQL Shell, use one
          of these options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <a class="link" href="programs.html#option_mysqlsh_mysqlx"><code class="option">--mysqlx</code></a> creates a
              Session, connected using X Protocol.
            </p></li><li class="listitem"><p>
              <a class="link" href="programs.html#option_mysqlsh_mysql"><code class="option">--mysql</code></a> creates a
              ClassicSession, connected using MySQL protocol.
</p></li></ul>
</div>
<p>
          To choose which type of session to use when defining a URI
          type string use one of these options:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              Specify <code class="literal">mysqlx</code> to create an
              X Protocol session. The X Plugin must be
              installed on the server instance, see
              <a class="xref" href="document-store.html" title="Chapter 20 Using MySQL as a Document Store">Chapter 20, <i>Using MySQL as a Document Store</i></a> for more information.
            </p></li><li class="listitem"><p>
              Specify <code class="literal">mysql</code> to create a classic MySQL
              protocol session.
</p></li></ul>
</div>
<p>
          For more information, see
          <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h5 class="title"><a name="mysql-shell-create-session-using-shell"></a>Creating a Session Using Shell Commands</h5>

</div>

</div>

</div>
<p>
          If you open MySQL Shell without specifying connection
          parameters, MySQL Shell opens without an established global
          session. It is possible to establish a global session once
          MySQL Shell has been started using the MySQL Shell
          <code class="literal">\connect <em class="replaceable"><code>URI</code></em></code>
          command, where <em class="replaceable"><code>URI</code></em> is a URI type
          string as defined at
          <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a>. For
          example:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
              <code class="literal">\connect -ma URI</code>: Creates a Session,
              automatically detecting the protocol. Attempts to use
              X Protocol by default, and falls back to MySQL
              protocol.
            </p></li><li class="listitem"><p>
              <code class="literal">\connect -mx | --mysqlx URI</code>: Creates a
              Session using X Protocol.
            </p></li><li class="listitem"><p>
              <code class="literal">\connect -mc | --mysql URI</code>: Creates a
              ClassicSession using MySQL protocol.
</p></li></ul>
</div>
<p>
          For example:
        </p><pre class="programlisting">
	mysql-js&gt; <strong class="userinput"><code>\connect mysqlx://user@localhost</code></strong>
</pre><p>
          Alternatively, use the
          <code class="literal">shell.connect('<em class="replaceable"><code>URI</code></em>'</code>
          method. For example this is equivalent to the above
          <code class="literal">\connect&gt;</code> command:
        </p><pre class="programlisting">
mysql-js&gt; <strong class="userinput"><code>shell.connect('mysqlx://user@localhost')</code></strong>
</pre>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-global-variables"></a>19.2.3 MySQL Shell Global Variables</h3>

</div>

</div>

</div>
<p>
      MySQL Shell reserves certain variables as global variables,
      which are assigned to commonly used objects in scripting. This
      section describes the available global variables and provides
      examples of working with them. The global variables are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          <code class="literal">session</code> represents the global session if
          one has been established.
        </p></li><li class="listitem"><p>
          <code class="literal">db</code> represents a schema if one has been
          defined, for example by a URI type string.
        </p></li><li class="listitem"><p>
          <code class="literal">dba</code> represents the AdminAPI, a component of
          InnoDB cluster which enables you to administer clusters of
          server instances. See
          <a class="xref" href="mysql-innodb-cluster-userguide.html" title="Chapter 21 InnoDB Cluster">Chapter 21, <i>InnoDB Cluster</i></a>.
        </p></li><li class="listitem"><p>
          <code class="literal">shell</code> provides general purpose functions,
          for example to configure MySQL Shell.
        </p></li><li class="listitem"><p>
          <code class="literal">util</code> provides utility functions, for
          example to check server instances before an upgrade.

          
</p></li></ul>
</div>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Important
</div>
<p>
        These words are reserved and cannot be used, for example as
        names of variables.
</p>
</div>
<p>
      By using these global objects, MySQL Shell provides interactive
      error resolution for common situations. For example:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Attempting to use an undefined <code class="literal">session</code>
          global variable.
        </p></li><li class="listitem"><p>
          Attempting to retrieve an nonexistent schema using
          <code class="literal">session</code>.
        </p></li><li class="listitem"><p>
          Attempting to use an undefined <code class="literal">db</code> global
          variable.
</p></li></ul>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-undefined-global-session"></a>Undefined Global Session</h4>

</div>

</div>

</div>
<p>
        The global <code class="literal">session</code> variable is set when a
        global session is established. When a global session is
        established, issuing a <code class="literal">session</code> statement in
        MySQL Shell displays the session type and its URI as follows:
      </p><pre class="programlisting">
mysql-js&gt; session
&lt;Session:root@localhost:33060&gt;
mysql-js&gt;
</pre><p>
        If no global session has been established, MySQL Shell
        displays the following:
      </p><pre class="programlisting">
mysql-js&gt; session
&lt;Undefined&gt;
mysql-js&gt;
</pre><p>
        If you attempt to use the <code class="literal">session</code> variable
        when no global session is established, interactive error
        resolution starts and you are prompted to provide the required
        information to establish a global session. If the session is
        successfully established, it is assigned to the
        <code class="literal">session</code> variable. The prompts are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            An initial prompt explains that no global session is
            established and asks if one should be established.
          </p></li><li class="listitem"><p>
            If you choose to set a global session, the session type is
            requested.
          </p></li><li class="listitem"><p>
            The URI type string to connect to the server instance is
            requested. See
            <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a>.
          </p></li><li class="listitem"><p>
            If required, a password is requested.
</p></li></ul>
</div>
<p>
        For example:
      </p><pre class="programlisting">
mysql-js&gt; session.uri
The global session is not set, do you want to establish a session?

   1) MySQL Document Store Session through X Protocol
   2) Classic MySQL Session

Please select the session type or ENTER to cancel: 2
Please specify the MySQL server URI: root@localhost
Enter password: 
root@localhost:
mysql-js&gt; session
&lt;ClassicSession:root@localhost:&gt;
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-undefined-db-variable"></a>Undefined db Variable</h4>

</div>

</div>

</div>
<p>
        The global <code class="literal">db</code> variable is set when a global
        session is established and a default schema is configured. For
        example, using a URI type string such as
        <code class="literal">root@localhost/sakila</code> to establish a global
        session connected to the MySQL Server at
        <code class="literal">localhost</code>, on port 33060, as the user
        <code class="literal">root</code>, assigns the schema
        <code class="literal">sakila</code> to the global variable
        <code class="literal">db</code>. Once a schema is defined, issuing
        <code class="literal">db</code> at the MySQL Shell prompt prints the
        schema name as follows:
      </p><pre class="programlisting">
mysql-js&gt; db
&lt;Schema:world_x&gt;
mysql-js&gt;
</pre><p>
        If there is no global session established, the following is
        displayed:
      </p><pre class="programlisting">
mysql-js&gt; db
&lt;Undefined&gt;
mysql-js&gt;
</pre><p>
        If you attempt to use the <code class="literal">db</code> variable when no
        global session has been established, the following error is
        displayed:
      </p><pre class="programlisting">
mysql-js&gt; db.getCollections()
LogicError: The db variable is not set, establish a global session first.
at (shell):1:2
in db.getCollections()
^
</pre><p>
        If a global session has been established but you attempt to use
        an undefined <code class="literal">db</code>, interactive error resolution
        begins and you are prompted to define an active schema by
        providing the schema name. If this succeeds the
        <code class="literal">db</code> variable is set to the defined schema. For
        example:
      </p><pre class="programlisting">
mysql-js&gt; db.getCollections()
The db variable is not set, do you want to set the active schema? [y/N]:y
Please specify the schema:world_x
[
&lt;Collection:countryinfo&gt;
]
mysql-js&gt; db
&lt;Schema:world_x&gt;
mysql-js&gt;
</pre>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-retrieving-a-nonexistent-schema"></a>Retrieving an Nonexistent Schema</h4>

</div>

</div>

</div>
<p>
        If you attempt to use <code class="literal">session</code> to retrieve an
        nonexistent schema, interactive error resolution provides the
        option to create the schema.
      </p><pre class="programlisting">
mysql-js&gt; var mySchema = session.getSchema('my_test')
The schema my_test does not exist, do you want to create it? [y/N]: y

mysql-js&gt; mySchema
&lt;Schema:my_test&gt;
mysql-js&gt;</pre><p>
        In all cases, if you do not provide the information required to
        resolve each situation, a proper result of executing the
        requested statement on an undefined variable is displayed.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-working-with-history"></a>19.2.4 MySQL Shell Code History</h3>

</div>

</div>

</div>
<p>
      Code which you issue in MySQL Shell is saved to the history,
      which can then be accessed using the up and down arrow keys. The
      <code class="literal">shell.options["history.autoSave"]</code> option must
      be set to ensure history is automatically saved.
    </p><p>
      History entries are saved to the
      <code class="filename">~/.mysqlsh/history</code> file on Linux and Mac, or
      the <code class="filename">%AppData%\MySQL\mysqlsh\history</code> file on
      Windows. The user configuration path can be overridden on all
      platforms by defining the environment variable
      <code class="varname">MYSQL_USER_CONFIG_HOME</code>. The value of this
      variable replaces <code class="filename">%AppData%\MySQL\mysqlsh\</code> on
      Windows or <code class="filename">~/.mysqlsh/</code> on Unix.
    </p><p>
      Issuing <code class="literal">\history</code> shows history entries in the
      order that they were issued with their history entry number, which
      can be used with the <code class="literal">\history delete
      <em class="replaceable"><code>entry_number</code></em></code> command. The
      numbering of history entries only resets after restarting
      MySQL Shell (or after issuing <code class="literal">\history
      clear</code>), meaning each entry keeps its entry number even
      when the oldest entries are discarded.
    </p><p>
      You can customize the entries added to the history using the
      <code class="option">--histignore</code> command option.
    </p><p>
      You can search the history using the incremental history search
      feature. To search the history, use control-r to search backwards,
      or control-s to search forwards through the history. Once the
      search is active, typing characters searches for any strings that
      match them in the history and displays the first match. Use
      control-s or control-r to search for further matches to the
      current search term. Typing more characters further refines the
      search. During a search you can press the arrow keys to continue
      stepping through the history from the current search result. Press
      Enter to accept the displayed match. Use control-c to cancel the
      search.
    </p><p>
      History entries are saved to the history file, which is readable
      only by the owner user and is created automatically by
      MySQL Shell. Only code which you type interactively at the
      MySQL Shell prompt is saved to the history. Code that is
      executed indirectly or internally, for example when the
      <code class="literal">\source</code> command is executed, is not added to
      the history. When you issue multi-line code, the new line
      characters are stripped in the history entry. If the same code is
      issued multiple times it is only stored in the history once,
      reducing duplication. The
      <code class="literal">shell.options["history.maxSize"]=number</code> option
      sets the maximum number of entries to store in the history, the
      default is 1000. If the number of history entries exceeds the
      configured maximum, the oldest entries are removed. If the maximum
      is set to 0, no history entries are saved. Old history entries are
      also deleted when MySQL Shell exits

      

      . If the history file cannot be read or written to, MySQL Shell
      logs an error message and skips the read or write operation.
    </p><p>
      Additionally, when using MySQL Shell in SQL mode, you can
      configure strings which should not be added to the history. By
      default strings that match the glob patterns
      <code class="literal">IDENTIFIED</code>, or <code class="literal">PASSWORD</code> are
      not added to the history. To configure further strings to match
      use either the <code class="option">--histignore</code> command option, or
      <code class="literal">shell.options["history.sql.ignorePattern"]</code>.
      Multiple strings can be specified, separated by a colon (:). The
      history matching uses case insensitive glob pattern like matching.
      Supported wildcards are * (match any 0 or more characters) and ?
      (match exactly 1 character). The default strings are specified as
      PASSWORD:IDENTIFIED.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-code-execution"></a>19.3 MySQL Shell Code Execution</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-interactive-code-execution">19.3.1 Interactive Code Execution</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-autocompletion">19.3.2 Code Autocompletion</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-batch-code-execution">19.3.3 Batch Code Execution</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-output-formats">19.3.4 Output Formats</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-active-language">19.3.5 Active Language</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-batch-mode-interactive">19.3.6 Batch Mode Made Interactive</a></span></dt></dl>
</div>
<p>
    This section explains how code execution works in MySQL Shell.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-interactive-code-execution"></a>19.3.1 Interactive Code Execution</h3>
</div>
</div>
</div>
<p>
      The default mode of MySQL Shell provides interactive execution
      of database operations that you type at the command prompt. These
      operations can be written in JavaScript, Python or SQL depending
      on the curent <a class="xref" href="mysql-shell.html#mysql-shell-active-language" title="19.3.5 Active Language">Section 19.3.5, “Active Language”</a>. When
      executed, the results of the operation are displayed on-screen.
    </p><p>
      As with any other language interpreter, MySQL Shell is very
      strict regarding syntax. For example, the following JavaScript
      snippet reads and prints the documents in a collection:
    </p><pre class="programlisting">
var mysqlx = require('mysqlx').mysqlx;
var mySession = mysqlx.getSession('user:pwd@localhost');
var result = mySession.world_x.countryinfo.find().execute();
var record = result.fetchOne();
while(record){
  print(record);
  record = result.fetchOne();
}
</pre><p>
      As seen above, the call to <code class="literal">find()</code> is followed
      by the <code class="literal">execute()</code> function. CRUD database
      commands are only actually executed on the MySQL Server when
      <code class="literal">execute()</code> is called. However, when working with
      MySQL Shell interactively, <code class="literal">execute()</code> is
      implicitly called whenever you press <code class="literal">Return</code> on
      a statement. Then the results of the operation are fetched and
      displayed on-screen. The rules for when you need to call
      <code class="literal">execute()</code> or not are as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          When using MySQL Shell in this way, calling
          <code class="literal">execute()</code> becomes optional on:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              <code class="literal">Collection.add()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Collection.find()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Collection.remove()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Collection.modify()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Table.insert()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Table.select()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Table.delete()</code>
            </p></li><li class="listitem"><p>
              <code class="literal">Table.update()</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
          Automatic execution is disabled if the object is assigned to a
          variable. In such a case calling <code class="literal">execute()</code>
          is mandatory to perform the operation.
        </p></li><li class="listitem"><p>
          When a line is processed and the function returns any of the
          available <code class="literal">Result</code> objects, the information
          contained in the Result object is automatically displayed on
          screen. The functions that return a Result object include:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              The SQL execution and CRUD operations (listed above)
            </p></li><li class="listitem"><p>
              Transaction handling and drop functions of the session
              objects in both mysql and mysqlx modules: -

</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p>
                    <code class="literal">startTransaction()</code>
                  </p></li><li class="listitem"><p>
                    <code class="literal">commit()</code>
                  </p></li><li class="listitem"><p>
                    <code class="literal">rollback()</code>
                  </p></li><li class="listitem"><p>
                    <code class="literal">dropSchema()</code>
                  </p></li><li class="listitem"><p>
                    <code class="literal">dropCollection()</code>
                  </p></li><li class="listitem"><p>
                    <code class="literal">ClassicSession.runSql()</code>
</p></li></ul>
</div>
<p>
</p></li></ul>
</div>
</li></ul>
</div>
<p>
      Based on the above rules, the statements needed in the
      MySQL Shell in interactive mode to establish a session, query,
      and print the documents in a collection are:
    </p><pre class="programlisting">
mysql-js&gt; <strong class="userinput"><code>var mysqlx = require('mysqlx').mysqlx;</code></strong>
mysql-js&gt; <strong class="userinput"><code>var mySession = mysqlx.getSession('user:pwd@localhost');</code></strong>
</pre><p>
      No call to <code class="literal">execute()</code> is needed and the Result
      object is automatically printed.
    </p><pre class="programlisting">
mysql-js&gt; <strong class="userinput"><code>mySession.world_x.countryinfo.find();</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-autocompletion"></a>19.3.2 Code Autocompletion</h3>

</div>

</div>

</div>
<p>
      MySQL Shell supports autocompletion of text preceding the cursor
      by pressing the <span class="keycap"><strong>Tab</strong></span> key. The
      <a class="xref" href="mysql-shell.html#mysql-shell-commands" title="19.4.1 MySQL Shell Commands">Section 19.4.1, “MySQL Shell Commands”</a> can be autocompleted in any
      of the language modes. For example typing
      <strong class="userinput"><code>\con</code></strong> and pressing the
      <code class="literal">Tab</code> key autocompletes to
      <strong class="userinput"><code>\connect</code></strong>. Autocompletion is available for
      SQL, JavaScript and Python language keywords depending on the
      current <a class="xref" href="mysql-shell.html#mysql-shell-active-language" title="19.3.5 Active Language">Section 19.3.5, “Active Language”</a>.
    </p><p>
      Autocompletion supports the following text objects:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          In SQL mode - autocompletion is aware of schema names, table
          names, column names of the current active schema.
        </p></li><li class="listitem"><p>
          In JavaScript and Python modes - autocompletion is aware of
          object members, for example:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
              global object names such as <code class="literal">session</code>,
              <code class="literal">db</code>, <code class="literal">dba</code>,
              <code class="literal">shell</code>, <code class="literal">mysql</code>,
              <code class="literal">mysqlx</code>, and so on.
            </p></li><li class="listitem"><p>
              members of global objects such as
              <code class="literal">session.connect()</code>,
              <code class="literal">dba.configureLocalInstance()</code>, and so
              on.
            </p></li><li class="listitem"><p>
              global user defined variables
            </p></li><li class="listitem"><p>
              chained object property references such as
              <code class="literal">shell.options.verbose</code>.
            </p></li><li class="listitem"><p>
              chained X DevAPI method calls such as
              <code class="literal">col.find().where().execute().fetchOne()</code>.
</p></li></ul>
</div>
</li></ul>
</div>
<p>
      By default autocompletion is enabled, to change this behavior see
      <a class="xref" href="mysql-shell.html#mysql-shell-configuring-autocompletion" title="Configuring Autocompletion">Configuring Autocompletion</a>.
    </p><p>
      Once you activate autocompletion, if the text preceding the cursor
      has exactly one possible match, the text is automatically
      completed. If autocompletion finds multiple possible matches, it
      beeps or flashes the terminal. If the <code class="literal">Tab</code> key
      is pressed again, a list of the possible completions is displayed.
      If no match is found then no autocompletion happens.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h4 class="title"><a name="mysql-shell-autocompleting-sql"></a>Autocompleting SQL</h4>
</div>
</div>
</div>
<p>
        When MySQL Shell is in SQL mode, autocompletion tries to
        complete any word with all possible completions that match. In
        SQL mode the following can be autocompleted:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            SQL keywords - List of known SQL keywords. Matching is
            case-insensitive.
          </p></li><li class="listitem"><p>
            SQL snippets - Certain common snippets, such as
            <a class="link" href="sql-syntax.html#show-create-table" title="13.7.6.10 SHOW CREATE TABLE Syntax"><code class="literal">SHOW CREATE TABLE</code></a>,
            <a class="link" href="sql-syntax.html#alter-table" title="13.1.8 ALTER TABLE Syntax"><code class="literal">ALTER TABLE</code></a>,
            <a class="link" href="sql-syntax.html#create-table" title="13.1.18 CREATE TABLE Syntax"><code class="literal">CREATE TABLE</code></a>, and so on.
          </p></li><li class="listitem"><p>
            Table names - If there is an active schema and database name
            caching is not disabled, all the tables of the active schema
            are used as possible completions.
</p></li></ul>
</div>
<p>
        As a special exception, if a backtick is found, only table names
        are considered for completion. In SQL mode, autocompletion is
        not context aware, meaning there is no filtering of completions
        based on the SQL grammar. In other words, autocompleting
        <strong class="userinput"><code>SEL</code></strong> returns
        <a class="link" href="sql-syntax.html#select" title="13.2.10 SELECT Syntax"><code class="literal">SELECT</code></a>, but it could also include
        a table called selfies.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-autocompleting-scripting"></a>Autocompleting JavaScript and Python</h4>

</div>

</div>

</div>
<p>
        In both JavaScript and Python modes, the string to be completed
        is determined from right to left, beginning at the current
        cursor position when <span class="keycap"><strong>Tab</strong></span> is pressed. Contents
        inside method calls are ignored, but must be syntactically
        correct. This means that strings, comments and nested method
        calls must all be properly closed and balanced. This allows
        chained methods to be handled properly. For example, when you
        are issuing:
      </p><pre data-lang="js" class="programlisting"><strong class="userinput"><code>print(db.user.select().where("user in ('foo', 'bar')").e</code></strong></pre><p>
        Pressing the <span class="keycap"><strong>Tab</strong></span> key would cause autocompletion
        to try to complete the text
        <strong class="userinput"><code>db.user.select().where().e</code></strong> but this
        invalid code yields undefined behavior. Any whitespace,
        including newlines, between tokens separated by a
        <code class="literal">.</code> is ignored.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-configuring-autocompletion"></a>Configuring Autocompletion</h4>

</div>

</div>

</div>
<p>
        By default the autocompletion engine is enabled. This section
        explains how to disable autocompletion and how to use the
        <code class="literal">\rehash</code> MySQL Shell command. Autocompletion
        uses a cache of database name objects that MySQL Shell is
        aware of. When autocompletion is enabled, this name cache is
        automatically updated. For example whenever you load a schema,
        the autocompletion engine updates the name cache based on the
        text objects found in the schema, so that you can autocomplete
        table names and so on.
      </p><p>
        To disable this behavior you can:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Start MySQL Shell with the
            <a class="link" href="programs.html#option_mysqlsh_no-name-cache"><code class="option">--no-name-cache</code></a> command
            option.
          </p></li><li class="listitem"><p>
            Modify the <code class="literal">autocomplete.nameCache</code> and
            <code class="literal">devapi.dbObjectHandles</code> keys of the
            <code class="literal">shell.options</code> to disable the
            autocompletion while MySQL Shell is running.
</p></li></ul>
</div>
<p>
        When the autocompletion name cache is disabled, you can manually
        update the text objects autocompletion is aware of by issuing
        <code class="literal">\rehash</code>. This forces a reload of the name
        cache based on the current active schema.
      </p><p>
        To disable autocompletion while MySQL Shell is running use the
        following <code class="literal">shell.options</code> keys:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">autocomplete.nameCache: boolean</code> toggles
            autocompletion name caching for use by SQL.
          </p></li><li class="listitem"><p>
            <code class="literal">devapi.dbObjectHandles: boolean</code> toggles
            autocompletion name caching for use by the X DevAPI
            <code class="literal">db</code> object, for example
            <code class="literal">db.mytable</code>,
            <code class="literal">db.mycollection</code>.
</p></li></ul>
</div>
<p>
        Both keys are set to <code class="literal">true</code> by default, and set
        to <code class="literal">false</code> if the
        <a class="link" href="programs.html#option_mysqlsh_no-name-cache"><code class="option">--no-name-cache</code></a> command option
        is used. To change the autocompletion name caching for SQL while
        MySQL Shell is running, issue:
      </p><pre data-lang="js" class="programlisting">
shell.options['autocomplete.nameCache']=true
</pre><p>
        Use the <code class="literal">\rehash</code> command to update the name
        cache manually.
      </p><p>
        To change the autocompletion name caching for JavaScript and
        Python while MySQL Shell is running, issue:
      </p><pre data-lang="js" class="programlisting">
shell.options['devapi.dbObjectHandles']=true
</pre><p>
        Again you can use the <code class="literal">\rehash</code> command to
        update the name cache manually.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-batch-code-execution"></a>19.3.3 Batch Code Execution</h3>

</div>

</div>

</div>
<p>
      As well as interactive code execution, MySQL Shell provides
      batch code execution from:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          A file loaded for processing.
        </p></li><li class="listitem"><p>
          A file containing code that is redirected to the standard
          input for execution.
        </p></li><li class="listitem"><p>
          Code from a different source that is redirected to the
          standard input for execution.
</p></li></ul>
</div>
<p>
      The input is processed based on the current programming language
      selected in MySQL Shell, which defaults to JavaScript. For
      example:
    </p><p>
      Loading JavaScript code from a file for batch processing.
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --file code.js</code></strong>
</pre><p>
      Redirecting a JavaScript file to standard input for execution.
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh &lt; code.js</code></strong>
</pre><p>
      Redirecting SQL to standard input for execution.
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>echo "show databases;" | mysqlsh --sql --uri root@198.51.100.141:33060</code></strong>
</pre>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h4 class="title"><a name="mysql-shell-executable-scripts"></a>Executable Scripts</h4>
</div>
</div>
</div>
<p>
        Starting with version 1.0.4, on Linux you can create executable
        scripts that run with MySQL Shell by including a
        <code class="literal">#!</code> line as the first line of the script. This
        line should provide the full path to MySQL Shell and include
        the <a class="link" href="programs.html#option_mysqlsh_file"><code class="option">--file</code></a> option. For example:
      </p><pre class="programlisting">
#!/usr/local/mysql-shell/bin/mysqlsh --file
print("Hello World\n");
</pre><p>
        The script file must be marked as executable in the filesystem.
        Running the script invokes MySQL Shell and it executes the
        contents of the script.
</p>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-output-formats"></a>19.3.4 Output Formats</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-output-table-format">19.3.4.1 Table Format</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-output-tab-format">19.3.4.2 Tab Separated Format</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-json-output">19.3.4.3 JSON Format Output</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-output-metadata">19.3.4.4 Result Metadata</a></span></dt></dl>
</div>
<p>
      The output of the commands processed on the server can be
      formatted in different ways. This section details the different
      available output formats.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-output-table-format"></a>19.3.4.1 Table Format</h4>
</div>
</div>
</div>
<p>
        The table format is used by default when MySQL Shell is in
        interactive mode. The output is presented as a formatted table
        for a better view and to aid analysis.
      </p><pre class="programlisting">
mysql-sql&gt; <strong class="userinput"><code>select * from sakila.actor limit 3;</code></strong>
+----------+-------------+----------------+----------------------+
| actor_id | first_name  | last_name      | last_update          |
+----------+-------------+----------------+----------------------+
|        1 | PENELOPE    | GUINESS        | 2006-02-15 4:34:33   |
|        2 | NICK        | WAHLBERG       | 2006-02-15 4:34:33   |
|        3 | ED          | CHASE          | 2006-02-15 4:34:33   |
+----------+-------------+----------------+----------------------+
3 rows in set (0.00 sec)

mysql-sql&gt;
</pre><p>
        To get this output format when running in batch mode, use the
        <a class="link" href="programs.html#option_mysqlsh_table"><code class="option">--table</code></a> command-line option.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-output-tab-format"></a>19.3.4.2 Tab Separated Format</h4>

</div>

</div>

</div>
<p>
        This format is used by default when running MySQL Shell in
        batch mode, to have better output for automated analysis.
      </p><pre class="programlisting">
&gt;<strong class="userinput"><code>echo "select * from sakila.actor limit 3;" | mysqlsh --classic --uri root@198.51.100.141:33460</code></strong>
actor_id        first_name      last_name       last_update
1       PENELOPE        GUINESS 2006-02-15 4:34:33
2       NICK    WAHLBERG        2006-02-15 4:34:33
3       ED      CHASE   2006-02-15 4:34:33
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-json-output"></a>19.3.4.3 JSON Format Output</h4>

</div>

</div>

</div>
<p>
        MySQL Shell supports the JSON format for output and it is
        available both in interactive and batch mode. This output format
        can be enabled using the <a class="link" href="programs.html#option_mysqlsh_json"><code class="option">--json</code></a>
        command-line option:
      </p><p>
        <span class="strong"><strong>JSON Format in Batch Mode</strong></span>
      </p><pre class="programlisting">
shell&gt;<strong class="userinput"><code>echo "select * from sakila.actor limit 3;" | mysqlsh --json --sqlc --uri root@198.51.100.141:3306</code></strong>
{"duration":"0.00 sec","info":"","row_count":3,"rows":[[1,"PENELOPE","GUINESS",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[2,"NICK","WAHLBERG",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[3,"ED","CHASE",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}]],"warning_count":0}

shell&gt;<strong class="userinput"><code>echo "select * from sakila.actor limit 3;" | mysqlsh --json=raw --sqlc --uri root@198.51.100.141:3306</code></strong>
{"duration":"0.00 sec","info":"","row_count":3,"rows":[[1,"PENELOPE","GUINESS",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[2,"NICK","WAHLBERG",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[3,"ED","CHASE",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}]],"warning_count":0}

shell&gt;<strong class="userinput"><code>echo "select * from sakila.actor limit 3;" | mysqlsh --json=pretty --sqlc --uri root@198.51.100.141:3306</code></strong>
{
    "duration": "0.00 sec",
    "info": "",
    "row_count": 3,
    "rows": [
        [
            1,
            "PENELOPE",
            "GUINESS",
            {
                "year": 2006,
                "month": 1,
                "day": 15,
                "hour": 4,
                "minute": 34,
                "second": 33.0
            }
        ],
        [
            2,
            "NICK",
            "WAHLBERG",
            {
                "year": 2006,
                "month": 1,
                "day": 15,
                "hour": 4,
                "minute": 34,
                "second": 33.0
            }
        ],
        [
            3,
            "ED",
            "CHASE",
            {
                "year": 2006,
                "month": 1,
                "day": 15,
                "hour": 4,
                "minute": 34,
                "second": 33.0
            }
        ]
    ],
    "warning_count": 0
}
shell&gt;
</pre><p>
        <span class="strong"><strong>JSON Format in Interactive Mode (started
        with --json=raw)</strong></span>
      </p><pre class="programlisting">
mysql-sql&gt; <strong class="userinput"><code>select * from sakila.actor limit 3;</code></strong>
{"duration":"0.00 sec","info":"","row_count":3,"rows":[[1,"PENELOPE","GUINESS",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[2,"NICK","WAHLBERG",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}],[3,"ED","CHASE",{"year":2006,"month":1,"day":15,"hour":4,"minute":34,"second":33.0}]],"warning_count":0}

mysql-sql&gt;
</pre><p>
        <span class="strong"><strong>JSON Format in Interactive Mode (started
        with --json=pretty)</strong></span>
      </p><pre class="programlisting">
mysql-sql&gt; <strong class="userinput"><code>select * from sakila.actor limit 3;</code></strong>
{
    "duration": "0.00 sec",
    "info": "",
    "row_count": 3,
    "rows": [
        [
            1,
            "PENELOPE",
            "GUINESS",
            {
                "year": 2006,
                "month": 1,
                "day": 15,
                "hour": 4,
                "minute": 34,
                "second": 33.0
            }
        ],
        [
            2,
            "NICK",
            "WAHLBERG",
            {
                "year": 2006,
                "month": 1,
                "day": 15,
                "hour": 4,
                "minute": 34,
                "second": 33.0
            }
        ],
        [
            3,
            "ED",
            "CHASE",
            {
                "year": 2006,
                "month": 1,
                "day": 15,
                "hour": 4,
                "minute": 34,
                "second": 33.0
            }
        ]
    ],
    "warning_count": 0
}

mysql-sql&gt;
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-output-metadata"></a>19.3.4.4 Result Metadata</h4>

</div>

</div>

</div>
<p>
        When an operation is executed, in addition to any results
        returned, some additional information is available. This
        includes information such as the number of affected rows,
        warnings, duration, and so on, when any of these conditions is
        true:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            JSON format is being used for the output
          </p></li><li class="listitem"><p>
            MySQL Shell is running in interactive mode.
</p></li></ul>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-active-language"></a>19.3.5 Active Language</h3>

</div>

</div>

</div>
<p>
      MySQL Shell can execute SQL, JavaScript or Python code, but only
      one language can be active at a time. The active mode determines
      how the executed statements are processed:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          If using SQL mode, statements are processed as SQL which means
          they are sent to the MySQL server for execution.
        </p></li><li class="listitem"><p>
          If using JavaScript mode, statements are processed as
          JavaScript code.
        </p></li><li class="listitem"><p>
          If using Python mode, statements are processed as Python code.
</p></li></ul>
</div>
<p>
      When running MySQL Shell in interactive mode, activate a
      specific language by entering the commands:
      <code class="literal">\sql</code>, <code class="literal">\js</code>,
      <code class="literal">\py</code>.
    </p><p>
      When running MySQL Shell in batch mode, activate a specific
      language by passing any of these command-line options:
      <a class="link" href="programs.html#option_mysqlsh_js"><code class="option">--js</code></a>,
      <a class="link" href="programs.html#option_mysqlsh_py"><code class="option">--py</code></a> or
      <a class="link" href="programs.html#option_mysqlsh_sql"><code class="option">--sql</code></a>. The default mode if none is
      specified is JavaScript.
    </p><p>
      Use MySQL Shell to execute the content of the file
      <code class="filename">code.sql</code> as SQL.
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --sql &lt; code.sql</code></strong>
</pre><p>
      Use MySQL Shell to execute the content of the file
      <code class="filename">code.js</code> as JavaScript code.
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh &lt; code.js</code></strong>
</pre><p>
      Use MySQL Shell to execute the content of the file
      <code class="filename">code.py</code> as Python code.
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --py &lt; code.py</code></strong>
</pre>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-batch-mode-interactive"></a>19.3.6 Batch Mode Made Interactive</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-multiple-line-support">19.3.6.1 Multiple-line Support</a></span></dt></dl>
</div>
<p>
      This section describes code execution in batch mode.
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          In batch mode, all the command logic described above is not
          available, only valid code for the active language can be
          executed.
        </p></li><li class="listitem"><p>
          When processing SQL code, it is executed statement by
          statement using the following logic: read/process/print
          result.
        </p></li><li class="listitem"><p>
          When processing non-SQL code, it is loaded entirely from the
          input source and executed as a unit.
</p></li></ul>
</div>
<p>
      Use the <a class="link" href="programs.html#option_mysqlsh_interactive"><code class="option">--interactive</code></a> (or
      <code class="option">-i</code>) command-line option to configure
      MySQL Shell to process the input source as if it were being
      issued in interactive mode; this enables all the features provided
      by the Interactive mode to be used in batch processing.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Note
</div>
<p>
        In this case, whatever the source is, it is read line by line
        and processed using the interactive pipeline.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-multiple-line-support"></a>19.3.6.1 Multiple-line Support</h4>

</div>

</div>

</div>
<p>
        It is possible to specify statements over multiple lines. When
        in Python or JavaScript mode, multiple-line mode is
        automatically enabled when a block of statements starts like in
        function definitions, if/then statements, for loops, and so on.
        In SQL mode multiple line mode starts when the command
        <code class="literal">\</code> is issued.
      </p><p>
        Once multiple-line mode is started, the subsequently entered
        statements are cached.
      </p><p>
        For example:
      </p><pre class="programlisting">
mysql-sql&gt; <strong class="userinput"><code>\</code></strong>
... <strong class="userinput"><code>create procedure get_actors()</code></strong>
... <strong class="userinput"><code>begin</code></strong>
... <strong class="userinput"><code>  select first_name from sakila.actor;</code></strong>
... <strong class="userinput"><code>end</code></strong>
...
mysql-sql&gt;
</pre>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-configuring"></a>19.4 Configuring MySQL Shell</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-commands">19.4.1 MySQL Shell Commands</a></span></dt></dl>
</div>
<p>
    This section explains how to configure MySQL Shell using commands
    executable from the interactive code editor and command options. For
    a description of MySQL Shell command options, see
    <a class="xref" href="programs.html#mysqlsh" title="4.5.7 mysqlsh — The MySQL Shell">Section 4.5.7, “<span class="command"><strong>mysqlsh</strong></span> — The MySQL Shell”</a>.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-commands"></a>19.4.1 MySQL Shell Commands</h3>
</div>
</div>
</div>
<p>
      MySQL Shell provides commands which enable you to modify the
      execution environment of the code editor, for example to configure
      the active programming language or a MySQL Server connection. The
      following table lists the commands that are available regardless
      of the currently selected language. As commands need to be
      available independent of the <span class="emphasis"><em>execution mode</em></span>,
      they start with an escape sequence, the <code class="literal">\</code>
      character.
</p>
<div class="informaltable">
<table summary="Commands available for MySQL Shell."><col width="20%"><col width="20%"><col width="60%"><thead><tr>
          <th scope="col">Command</th>
          <th scope="col">Alias/Shortcut</th>
          <th scope="col">Description</th>
        </tr></thead><tbody><tr>
          <td scope="row"><p>
              <code class="literal">\help</code>
            </p></td>
          <td><p>
              <code class="literal">\h</code> or <code class="literal">\?</code>
            </p></td>
          <td><p>
              Prints help about MySQL Shell commands.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\quit</code>
            </p></td>
          <td><p>
              <code class="literal">\q</code> or <code class="literal">\exit</code>
            </p></td>
          <td><p>
              Exit MySQL Shell.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\</code>
            </p></td>
          <td></td>
          <td><p>
              In SQL mode, begin multiple-line mode. Code is cached and
              executed when an empty line is entered.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\status</code>
            </p></td>
          <td><p>
              <code class="literal">\s</code>
            </p></td>
          <td><p>
              Show the current MySQL Shell status.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\js</code>
            </p></td>
          <td></td>
          <td><p>
              Switch execution mode to JavaScript.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\py</code>
            </p></td>
          <td></td>
          <td><p>
              Switch execution mode to Python.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\sql</code>
            </p></td>
          <td></td>
          <td><p>
              Switch execution mode to SQL.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\connect</code>
            </p></td>
          <td><p>
              <code class="literal">\c</code>
            </p></td>
          <td><p>
              Connect to a MySQL Server
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\reconnect</code>
            </p></td>
          <td></td>
          <td><p>
              Reconnect to the same MySQL Server
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\use</code>
            </p></td>
          <td><p>
              <code class="literal">\u</code>
            </p></td>
          <td><p>
              Specify the schema to use.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\source</code>
            </p></td>
          <td><p>
              <code class="literal">\.</code>
            </p></td>
          <td><p>
              Execute a script file using the active language.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\warnings</code>
            </p></td>
          <td><p>
              <code class="literal">\W</code>
            </p></td>
          <td><p>
              Show any warnings generated by a statement.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\nowarnings</code>
            </p></td>
          <td><p>
              <code class="literal">\w</code>
            </p></td>
          <td><p>
              Do not show any warnings generated by a statement.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\history</code>
            </p></td>
          <td></td>
          <td><p>
              View and edit command line history.
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              <code class="literal">\rehash</code>
            </p></td>
          <td></td>
          <td><p>
              Manually update the autocomplete name cache
            </p></td>
</tr></tbody></table>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489300192"></a>Help Command</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">\help</code> command can be used with or without
        parameters. When used without parameters a general help is
        printed including information about:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Available commands.
          </p></li><li class="listitem"><p>
            Available commands for the active mode.
</p></li></ul>
</div>
<p>
        When used with a parameter, the parameter must be a valid
        command. If that is the case, help for that specific command is
        printed including:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Description
          </p></li><li class="listitem"><p>
            Supported aliases if any
          </p></li><li class="listitem"><p>
            Additional help if any
</p></li></ul>
</div>
<p>
        For example:
      </p><pre class="programlisting">
<strong class="userinput"><code>\help connect</code></strong>
</pre><p>
        If the parameter is not a valid command, the general help is
        printed.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489290336"></a>Connect and Reconnect Commands</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">\connect</code> command is used to connect to a
        MySQL Server using an URI type string. See
        <a class="xref" href="mysql-shell.html#mysql-shell-connection-using-uri" title="19.2.1.1 Connecting using a URI String">Section 19.2.1.1, “Connecting using a URI String”</a>.
      </p><p>
        For example:
      </p><pre class="programlisting">
<strong class="userinput"><code>\connect root@localhost:3306</code></strong>
</pre><p>
        If a password is required you are prompted for it.
      </p><p>
        Use the <code class="literal">--mysqlx</code>(<code class="literal">-mx</code>)
        option to create a session using the X Protocol to connect
        to MySQL server instance. For example:
      </p><pre class="programlisting">
<strong class="userinput"><code>\connect --mysqlx root@localhost:33060</code></strong>
</pre><p>
        Use the <code class="literal">--mysql</code>(<code class="literal">-mc</code>)
        option to create a ClassicSession, enabling you to use the MySQL
        protocol to issue SQL directly on a server. For example:
      </p><pre class="programlisting">
<strong class="userinput"><code>\connect --mysql root@localhost:3306</code></strong>
</pre><p>
        The <code class="literal">\reconnect</code> command is specified without
        any parameters or options. If the connection to the server is
        lost, you can use the <code class="literal">\reconnect</code> command,
        which makes MySQL Shell try several reconnection attempts for
        the session using the existing connection parameters. If those
        attempts are unsuccessful, you can make a fresh connection using
        the <code class="literal">\connect</code> command and specifying the
        connection parameters.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489275840"></a>Status Command</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">\status</code> command displays information
        about the current global connection. This includes information
        about the server connected to, the character set in use, uptime,
        and so on.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489273728"></a>Source Command</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">\source</code> command is used to execute code
        from a script at a given path. For example:
      </p><pre class="programlisting">
<strong class="userinput"><code>\source /tmp/mydata.sql</code></strong>
</pre><p>
        You can execute either SQL, JavaScript or Python code. The code
        in the file is executed using the active language, so to process
        SQL code the MySQL Shell must be in SQL mode.
</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">

<div class="admon-title">
Warning
</div>
<p>
          As the code is executed using the active language, executing a
          script in a different language than the currently selected
          execution mode language could lead to unexpected results.
</p>
</div>

</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489268752"></a>Use Command</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">\use</code> command enables you to choose which
        schema is active, for example:
      </p><pre class="programlisting"><strong class="userinput"><code>\use <em class="replaceable"><code>schema_name</code></em></code></strong></pre><p>
        The <code class="literal">\use</code> command requires a global
        development session to be active. The <code class="literal">\</code>use
        command sets the current schema to the specified
        <em class="replaceable"><code>schema_name</code></em> and updates the
        <code class="literal">db</code> variable to the object that represents the
        selected schema.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489262224"></a>History Command</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">\history</code> command lists the commands you
        have issued previously in MySQL Shell. Issuing
        <code class="literal">\history</code> shows history entries in the order
        that they were issued with their history entry number, which can
        be used with the <code class="literal">\history delete
        <em class="replaceable"><code>entry_number</code></em></code> command.
      </p><p>
        The <code class="literal">\history</code> command provides the following:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            Use <code class="literal">\history save</code> to save the history
            manually.
          </p></li><li class="listitem"><p>
            Use <code class="literal">\history delete entrynumber</code> to delete
            a history entry with the given number.
          </p></li><li class="listitem"><p>
            Use <code class="literal">\history delete
            <em class="replaceable"><code>firstnumber</code></em>-[<em class="replaceable"><code>lastnumber</code></em>]</code>
            to delete history entries within the range of the given
            entry numbers. If <em class="replaceable"><code>lastnumber</code></em> is
            ommitted, history entries are deleted from
            <em class="replaceable"><code>firstnumber</code></em> up to the last entry.
            If <em class="replaceable"><code>lastnumber</code></em> goes past the last
            found history entry number, it deletes up to the last entry.
          </p></li><li class="listitem"><p>
            Use <code class="literal">\history clear</code> to delete the entire
            history.
</p></li></ul>
</div>
<p>
        For more information, see
        <a class="xref" href="mysql-shell.html#mysql-shell-working-with-history" title="19.2.4 MySQL Shell Code History">Section 19.2.4, “MySQL Shell Code History”</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="idm139899489246800"></a>Rehash Command</h4>

</div>

</div>

</div>
<p>
        When you have disabled the autocomplete name cache feature, use
        the <code class="literal">\rehash</code> command to manually update the
        cache. For example, after you load a new schema by issuing the
        <code class="literal">\use <em class="replaceable"><code>schema</code></em></code>
        command, issue <code class="literal">\rehash</code> to update the
        autocomplete name cache. After this autocomplete is aware of the
        names used in the database, and you can autocomplete text such
        as table names and so on.

</p>
</div>

</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-utilities"></a>19.5 MySQL Shell Utilities</h2>

</div>

</div>

</div>
<p>
    MySQL Shell includes utilities for working with MySQL. To access
    the utilities use the <code class="literal">util</code> global object, which
    includes the
    <code class="literal">checkForServerUpgrade(<em class="replaceable"><code>instance</code></em>
    [,<em class="replaceable"><code>password]</code></em>)</code> operation that
    enables you to verify server instances are suitable for upgrade to
    MySQL 8. If you issue <code class="literal">checkForServerUpgrade()</code>
    without specifying an <em class="replaceable"><code>instance</code></em>, the
    instance currently connected to the global session is checked.
    Provide the password for the user either as part of the connection
    details or as the second element passed to the operation. To verify
    the server at URI type string
    <code class="literal">user@example.com:3306</code> issue:
  </p><pre data-lang="js" class="programlisting">
mysqlsh&gt; <strong class="userinput"><code>util.checkForServerUpgrade('user@example.com:3306', 'password')</code></strong>
</pre><p>
    MySQL Shell connects to the server instance and tests the settings
    described at <a class="xref" href="installing.html#upgrade-prerequisites" title="Verifying Upgrade Prerequisites for Your MySQL 5.7 Installation">Verifying Upgrade Prerequisites for Your MySQL 5.7
          Installation</a>. For example:
  </p><pre data-lang="simple" class="programlisting">
The MySQL server at example.com:3306 will now be checked for compatibility issues for upgrade to MySQL 8.0...
MySQL version: 5.7.21 - MySQL Community Server (GPL)

1) Usage of db objects with names conflicting with reserved keywords in 8.0
  No issues found

2) Usage of utf8mb3 charset
  No issues found

3) Usage of use ZEROFILL/display length type attributes
  No issues found

4) Issues reported by 'check table x for upgrade' command
  No issues found

5) Table names in the mysql schema conflicting with new tables in 8.0
  No issues found

6) Usage of old temporal type
  No issues found

7) Foreign key constraint names longer than 64 characters
  No issues found

8) Usage of obsolete MAXDB sql_mode flag
  No issues found

9) Usage of obsolete sql_mode flags
  No issues found

10) Usage of partitioned tables in shared tablespaces
  No issues found

11) Usage of removed functions
  No issues found

No known compatibility errors or issues for upgrading the target server to MySQL 8 were found.
  </pre><p>
    In this case the server instance being checked passed all of the
    tests and can be upgraded to MySQL 8. A server instance that fails
    any of the tests requires changes before it can be upgraded to MySQL
    8. A server that generates warnings can be upgraded to MySQL 8, but
    the configuration could be improved to make the server more
    compatible with MySQL 8. The return value of
    <strong class="userinput"><code>util.checkForServerUpgrade()</code></strong> is:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        <code class="literal">0</code> if no issues found
      </p></li><li class="listitem"><p>
        <code class="literal">1</code> if warnings were found
      </p></li><li class="listitem"><p>
        <code class="literal">2</code> if errors were found
</p></li></ul>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-application-log"></a>19.6 MySQL Shell Application Log</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-application-log-introduction">19.6.1 Application Log</a></span></dt></dl>
</div>
<p>
    This section explains the application log.
</p>
<div class="section">

<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-application-log-introduction"></a>19.6.1 Application Log</h3>
</div>
</div>
</div>
<p>
      MySQL Shell can be configured to generate an application log
      file with information about issues of varying severity. You can
      use this information to verify the state of MySQL Shell while it
      is running.
    </p><p>
      The location of the log file is the user configuration path and
      the file is named <code class="filename">mysqlsh.log</code>.
</p>
<h4><a name="idm139899489219360"></a>Log File on Windows</h4>
<p>
      On Windows, the default path to the log file is
      <code class="filename">%APPDATA%\MySQL\mysqlsh\mysqlsh.log</code>
    </p><p>
      To find the location of <code class="filename">%APPDATA%</code> on your
      system, echo it from the comand-line. For example:
    </p><pre class="programlisting">
C:&gt;<strong class="userinput"><code>echo %APPDATA%</code></strong>

C:\Users\exampleuser\AppData\Roaming
</pre><p>
      On Windows, the path is determined by the result of gathering the
      <code class="filename">%APPDATA%</code> folder specific to that user, and
      then appending <code class="filename">MySQL\mysqlsh</code>. Using the above
      example, we end up with:

</p><pre class="programlisting">
C:\Users\exampleuser\AppData\Roaming\MySQL\mysqlsh\mysqlsh.log
</pre><p>
</p>
<h4><a name="idm139899489212208"></a>Log File on Unix-based Systems</h4>
<p>
      For a machine running Unix, the default path is
      <code class="filename">~/.mysqlsh/mysqlsh.log</code> where <span class="quote">“<span class="quote">~</span>”</span>
      represents the user's home directory. The environment variable
      <code class="varname">HOME</code> also represents the user's home directory.
      Appending <code class="filename">.mysqlsh</code> to the user's home
      directory determines the default path to the logs. For example:
    </p><pre class="programlisting">
C:&gt;<strong class="userinput"><code>echo $HOME</code></strong>

/home/exampleuser

shell&gt; <strong class="userinput"><code>less /home/exampleuser/.mysqlsh/mysqlsh.log</code></strong>
</pre><p>
      The default user configuration path can be overridden on all
      platforms by defining the environment variable
      <code class="varname">MYSQL_USER_CONFIG_HOME</code>. The value of this
      variable replaces <code class="filename">%AppData%\MySQL\mysqlsh\</code> on
      Windows or <code class="filename">~/.mysqlsh/</code> on Unix.
    </p><p>
      By default, logging is disabled in MySQL Shell. To enable
      logging use the <a class="link" href="programs.html#option_mysqlsh_log-level"><code class="option">--log-level</code></a>
      command-line option when starting MySQL Shell. For example:
    </p><pre class="programlisting">
shell&gt; <strong class="userinput"><code>mysqlsh --log-level=4</code></strong>
</pre><p>
      The number assigned to <a class="link" href="programs.html#option_mysqlsh_log-level"><code class="option">--log-level</code></a>
      controls the level of detail in the log. The following logging
      levels are supported:
</p>
<div class="informaltable">
<table summary="Logging levels that are supported for --log-level."><col width="40%"><col width="60%"><thead><tr>
          <th scope="col">Log Level</th>
          <th scope="col">Meaning</th>
        </tr></thead><tbody><tr>
          <td scope="row"><p>
              1
            </p></td>
          <td><p>
              None, the default
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              2
            </p></td>
          <td><p>
              Internal Error
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              3
            </p></td>
          <td><p>
              Error
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              4
            </p></td>
          <td><p>
              Warning
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              5
            </p></td>
          <td><p>
              Info
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              6
            </p></td>
          <td><p>
              Debug
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              7
            </p></td>
          <td><p>
              Debug2
            </p></td>
        </tr><tr>
          <td scope="row"><p>
              8
            </p></td>
          <td><p>
              Debug3
            </p></td>
</tr></tbody></table>
</div>
<p>
      The log format is plain text and entries contain a timestamp and
      description of the problem, along with the log level from the
      above list. For example:
    </p><pre class="programlisting">
2016-04-05 22:23:01: Error: Default Domain: (shell):1:8: MySQLError: You have an error
in your SQL syntax; check the manual that corresponds to your MySQL server version for
the right syntax to use near '' at line 1 (1064) in session.sql("select * from t
limit").execute().all();
</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a name="mysql-shell-customizing"></a>19.7 Customizing MySQL Shell</h2>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-creating-startup-scripts">19.7.1 Working With Start-Up Scripts</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-adding-module-search-paths">19.7.2 Adding Module Search Paths</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-prompt-themes">19.7.3 Customizing the Prompt</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-configuring-options">19.7.4 Configuring MySQL Shell</a></span></dt></dl>
</div>
<p>
    MySQL Shell offers the ability to customize the behavior and code
    execution environment through startup scripts, which are executed
    when the application is first run. Using such scripts enables you
    to:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
        Add additional search paths for Python or JavaScript modules.
      </p></li><li class="listitem"><p>
        Override the default prompt used by the Python and JavaScript
        modes.
      </p></li><li class="listitem"><p>
        Define global functions or variables.
      </p></li><li class="listitem"><p>
        Any other possible initialization through JavaScript or Python.
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-creating-startup-scripts"></a>19.7.1 Working With Start-Up Scripts</h3>

</div>

</div>

</div>
<p>
      When MySQL Shell enters either into JavaScript or Python mode,
      it searches for startup scripts to be executed. The startup
      scripts are JavaScript or Python specific scripts containing the
      instructions to be executed when the corresponding mode is
      initialized.
    </p><p>
      Startup scripts must be named as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          For JavaScript mode: <code class="filename">mysqlshrc.js</code>
        </p></li><li class="listitem"><p>
          For Python mode: <code class="filename">mysqlshrc.py</code>
</p></li></ul>
</div>
<p>
      MySQL Shell searches the following paths for these files (in
      order of execution).
    </p><p>
      On Windows:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          <code class="literal">%PROGRAMDATA%\MySQL\mysqlsh\mysqlshrc.[js|py]</code>
        </p></li><li class="listitem"><p>
          <code class="literal">%MYSQLSH_HOME%\shared\mysqlsh\mysqlshrc.[js|py]</code>
        </p></li><li class="listitem"><p>
          <code class="literal">&lt;mysqlsh binary
          path&gt;\mysqlshrc.[js|py]</code>
        </p></li><li class="listitem"><p>
          <code class="literal">%APPDATA%\MySQL\mysqlsh\mysqlshrc.[js|py]</code>
</p></li></ol>
</div>
<p>
      On Linux and OSX:
</p>
<div class="orderedlist">
<ol class="orderedlist" type="1"><li class="listitem"><p>
          <code class="literal">/etc/mysql/mysqlsh/mysqlshrc.[js|py]</code>
        </p></li><li class="listitem"><p>
          <code class="literal">$MYSQLSH_HOME/shared/mysqlsh/mysqlshrc.[js|py]</code>
        </p></li><li class="listitem"><p>
          <code class="literal">&lt;mysqlsh binary
          path&gt;/mysqlshrc.[js|py]</code>
        </p></li><li class="listitem"><p>
          <code class="literal">$HOME/.mysqlsh/mysqlshrc.[js|py]</code>
</p></li></ol>
</div>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Warning
</div>
<p>
        The lists above also define the order of searching the paths, so
        if something is defined in two different scripts, the script
        executed later takes precedence.
</p>
</div>
<p>
      The environment variable <code class="literal">MYSQLSH_HOME</code>, used in
      option 2, defines the root folder of a standard setup of
      MySQL Shell. If <code class="literal">MYSQLSH_HOME</code> is not defined
      it is automatically calculated based on the location of the
      MySQL Shell binary, therefore on many standard setups it is not
      required to define <code class="literal">MYSQLSH_HOME</code>.
    </p><p>
      If <code class="literal">MYSQLSH_HOME</code> is not defined and the
      MySQL Shell binary is not in a standard install folder
      structure, then the path defined in option 3 in the above lists is
      used. If using a standard install or if
      <code class="literal">MYSQLSH_HOME</code> points to a standard install
      folder structure, then the path defined in option 3 is not used.
    </p><p>
      The user configuration path in option 4 can be overridden on all
      platforms by defining the environment variable
      <code class="varname">MYSQL_USER_CONFIG_HOME</code>. The value of this
      variable replaces <code class="filename">%AppData%\MySQL\mysqlsh\</code> on
      Windows or <code class="filename">~/.mysqlsh/</code> on Unix.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-adding-module-search-paths"></a>19.7.2 Adding Module Search Paths</h3>

</div>

</div>

</div>
<div class="toc">
<dl class="toc"><dt><span class="section"><a href="mysql-shell.html#mysql-shell-environment-variables">19.7.2.1 Environment Variables</a></span></dt><dt><span class="section"><a href="mysql-shell.html#mysql-shell-startup-scripts">19.7.2.2 Startup Scripts</a></span></dt></dl>
</div>
<p>
      

      There are two ways to add additional module search paths:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          Through environment variables
        </p></li><li class="listitem"><p>
          Through startup scripts
</p></li></ul>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-environment-variables"></a>19.7.2.1 Environment Variables</h4>

</div>

</div>

</div>
<p>
        Python uses the <code class="literal">PYTHONPATH</code> environment
        variable to allow extending the search paths for python modules.
        The value of this variable is a list of paths separated by:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            A colon character in Linux and OSX
          </p></li><li class="listitem"><p>
            A semicolon character in Windows
</p></li></ul>
</div>
<p>
        To achieve this in JavaScript, MySQL Shell supports defining
        additional JavaScript module paths using the
        <code class="literal">MYSQLSH_JS_MODULE_PATH</code> environment variable.
        The value of this variable is a list of semicolon separated
        paths.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name="mysql-shell-startup-scripts"></a>19.7.2.2 Startup Scripts</h4>

</div>

</div>

</div>
<p>
        The addition of module search paths can be achieved for both
        languages through the corresponding startup script.
      </p><p>
        For Python modify the <code class="filename">mysqlshrc.py</code> file and
        append the required paths into the <code class="literal">sys.path</code>
        array.
      </p><pre class="programlisting">
# Import the sys module
import sys

# Append the additional module paths
sys.path.append('~/custom/python')
sys.path.append('~/other/custom/modules')</pre><p>
        For JavaScript the same task is achieved by adding code into the
        <code class="filename">mysqlshrc.js</code> file to append the required
        paths into the predefined
        <code class="literal">shell.js_module_paths</code> array.
      </p><pre class="programlisting">
// Append the additional module paths
shell.js.module_paths[shell.js.module_paths.length] = '~/custom/js';
shell.js.module_paths[shell.js.module_paths.length] = '~/other/custom/modules';</pre>
</div>

</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-prompt-themes"></a>19.7.3 Customizing the Prompt</h3>

</div>

</div>

</div>
<p>
      The prompt of MySQL Shell can be customized using prompt theme
      files. To customze the prompt theme file, either set the
      <code class="literal">MYSQLSH_PROMPT_THEME</code> environment variable to a
      prompt theme file name, or copy a theme file to the
      <code class="filename">~/.mysqlsh/prompt.json</code> directory on Linux and
      Mac, or the
      <code class="filename">%AppData%\MySQL\mysqlsh\prompt.json</code> directory
      on Windows.
    </p><p>
      The user configuration path for the directory can be overridden on
      all platforms by defining the environment variable
      <code class="varname">MYSQL_USER_CONFIG_HOME</code>. The value of this
      variable replaces <code class="filename">%AppData%\MySQL\mysqlsh\</code> on
      Windows or <code class="filename">~/.mysqlsh/</code> on Unix.
    </p><p>
      The format of the prompt theme file is described in the
      <code class="filename">README.prompt</code> file, and some sample prompt
      theme files are included.

      

      Some of the sample prompt theme files require a special font (for
      example
      <code class="literal">SourceCodePro+Powerline+Awesome+Regular.ttf</code>),
      or support from the terminal for color display. Most terminals
      support 256 colors in Linux and Mac. In Windows, color support
      requires either a 3rd party terminal program with support for
      ANSI/VT100 escapes, or Windows 10. On startup, if an error is
      found in the prompt theme file, an error message is printed and a
      default prompt theme is used.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name="mysql-shell-configuring-options"></a>19.7.4 Configuring MySQL Shell</h3>

</div>

</div>

</div>
<p>
      You can configure MySQL Shell to match your preferences, for
      example to start up to a certain programming language or to
      customize output and so on. Configuration options can be set for
      only the current session, or options can be set permanently by
      persisting changes to the MySQL Shell configuration file. Online
      help for all options is provided. You can configure options using
      either MySQL Shell command, which is available in all
      MySQL Shell modes for querying and changing configuration
      options. Alternatively in JavaScript and Python modes, use the
      <code class="literal">shell.options</code> object.
    </p><p>
      This section describes which options are available and how to
      configure them.
</p>
<div class="simplesect">

<div class="titlepage">
<div>

<div class="simple">
<h4 class="title"><a name="mysql-shell-configuring-command-interface"></a>Using the <code class="literal">\option</code> Command</h4>
</div>
</div>
</div>
<p>
        The MySQL Shell <code class="literal">\option</code> command enables you
        to query and change configuration options in all modes, enabling
        configuration from SQL mode in addition to JavaScript and Python
        modes.
      </p><p>
        The command is used as follows:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">\option -h, --help [&lt;filter&gt;]</code> -
            print help for options matching filter.
          </p></li><li class="listitem"><p>
            <code class="literal">\option -l, --list [--show-origin]</code> - list
            all the options. <code class="literal">--show-origin</code> augments
            the list with information about how the value was last
            changed, possible values are:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>
                <code class="literal">Command line</code>
              </p></li><li class="listitem"><p>
                <code class="literal">Compiled default</code>
              </p></li><li class="listitem"><p>
                <code class="literal">Configuration file</code>
              </p></li><li class="listitem"><p>
                <code class="literal">Environment variable</code>
              </p></li><li class="listitem"><p>
                <code class="literal">User defined</code>
</p></li></ul>
</div>
</li><li class="listitem"><p>
            <code class="literal">\option
            <em class="replaceable"><code>option_name</code></em></code> - print
            value of the option.
          </p></li><li class="listitem"><p>
            <code class="literal">\option [--persist]
            <em class="replaceable"><code>option_name</code></em>
            <em class="replaceable"><code>value</code></em> or
            <em class="replaceable"><code>name=value</code></em></code> - set value
            of the option and if <code class="literal">--persist</code> is
            specified save it to the configuration file.
          </p></li><li class="listitem"><p>
            <code class="literal">\option --unset [--persist]
            &lt;option_name&gt;</code> - reset option's value to
            default and if <code class="literal">--persist</code> is specified,
            removes the option from configuration file.
</p></li></ul>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          the <em class="replaceable"><code>option_name</code></em> and
          <em class="replaceable"><code>filter</code></em> are case sensitive.
</p>
</div>
<p>
        See <a class="xref" href="mysql-shell.html#mysql-shell-configuration-valid-options" title="Valid Configuration Options">Valid Configuration Options</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-configuring-script-interface"></a>Using the <code class="literal">shell.options</code> Configuration Interface</h4>

</div>

</div>

</div>
<p>
        The <code class="literal">shell.options</code> object is available in
        JavaScript and Python mode to read and change option values. In
        addition to the dictionary like interface, the following methods
        are available:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            <code class="literal">shell.options.set(<em class="replaceable"><code>optionName</code></em>,
            <em class="replaceable"><code>value</code></em>)</code> - sets the
            <em class="replaceable"><code>optionName</code></em> to
            <em class="replaceable"><code>value</code></em> for this session, the
            change is not saved to the configuration file
          </p></li><li class="listitem"><p>
            <code class="literal">shell.options.set_persist(<em class="replaceable"><code>optionName</code></em>,
            <em class="replaceable"><code>value</code></em>)</code> - sets the
            <em class="replaceable"><code>optionName</code></em> to
            <em class="replaceable"><code>value</code></em> for this session, and saves
            the change to the configuration file
          </p></li><li class="listitem"><p>
            <code class="literal">shell.options.unset(<em class="replaceable"><code>optionName</code></em>)</code>
            - resets the <em class="replaceable"><code>optionName</code></em> to no
            value

            

            for this session, the change is not saved to the
            configuration file
          </p></li><li class="listitem"><p>
            <code class="literal">shell.options.unset_persist(<em class="replaceable"><code>optionName</code></em>)</code>
            - resets the <em class="replaceable"><code>optionName</code></em> to no
            value

            

            for this session, and saves the change to the configuration
            file
</p></li></ul>
</div>
<p>
        See <a class="xref" href="mysql-shell.html#mysql-shell-configuration-valid-options" title="Valid Configuration Options">Valid Configuration Options</a>.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-configuration-file"></a>Configuration File</h4>

</div>

</div>

</div>
<p>
        The MySQL Shell configuration file stores the values of the
        option to ensure they are persisted across sessions. Values are
        read at startup and when you use the persist feature, settings
        are saved to the configuration file.
      </p><p>
        The location of the configuration file is the user configuration
        path and the file is named <code class="filename">options.json</code>.
        Assuming that the default user configuration path has not been
        overridden by defining the environment variable
        <code class="literal">MYSQL_USER_CONFIG_HOME</code>, the path to the
        configuration file is:
</p>
<div class="itemizedlist">
<ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
            on Windows <code class="filename">%APPDATA%\MySQL\mysqlsh</code>
          </p></li><li class="listitem"><p>
            on Unix <code class="filename">~/.mysqlsh</code> where
            <code class="literal">~</code> represents the user's home directory.
</p></li></ul>
</div>
<p>
        The configuration file is created the first time you customize a
        configuration option. This file is internally maintained by
        MySQL Shell and should not be edited manually. If an
        unrecognized option or an option with an incorrect value is
        found in the configuration file on startup, MySQL Shell exits
        with an error.
</p>
</div>
<div class="simplesect">
<div class="titlepage">
<div>
<div class="simple">
<h4 class="title"><a name="mysql-shell-configuration-valid-options"></a>Valid Configuration Options</h4>

</div>

</div>

</div>
<p>
        The following configuration options can be set using either the
        <code class="literal">\option</code> command or
        <code class="literal">shell.options</code> scripting interface:
</p>
<div class="informaltable">
<table><col width="33%" align="left"><col width="33%" align="left"><col width="34%" align="left"><thead><tr>
            <th scope="col">optionName</th>
            <th scope="col">DefaultValue</th>
            <th scope="col">Type</th>
          </tr></thead><tbody><tr>
            <td scope="row">autocomplete.nameCache</td>
            <td>true</td>
            <td>boolean</td>
          </tr><tr>
            <td scope="row">batchContinueOnError</td>
            <td>false</td>
            <td>boolean (READ ONLY)</td>
          </tr><tr>
            <td scope="row">devapi.dbObjectHandles</td>
            <td>true</td>
            <td>boolean</td>
          </tr><tr>
            <td scope="row">history.autoSave</td>
            <td>false</td>
            <td>boolean</td>
          </tr><tr>
            <td scope="row">history.maxSize</td>
            <td>1000</td>
            <td>integer</td>
          </tr><tr>
            <td scope="row">history.sql.ignorePattern</td>
            <td>*IDENTIFIED* : *PASSWORD*</td>
            <td>string</td>
          </tr><tr>
            <td scope="row">interactive</td>
            <td>true</td>
            <td>boolean (READ ONLY)</td>
          </tr><tr>
            <td scope="row">logLevel</td>
            <td>5</td>
            <td>integer ranging from 1 to 8</td>
          </tr><tr>
            <td scope="row">outputFormat</td>
            <td>table</td>
            <td>string (table, vertical, json, json/raw, tabbed)</td>
          </tr><tr>
            <td scope="row">passwordsFromStdin</td>
            <td>false</td>
            <td>boolean</td>
          </tr><tr>
            <td scope="row">sandboxDir</td>
            <td>C:\Users\MyUser\MySQL\mysql-sandboxes or $HOME/mysql-sandboxes</td>
            <td>string</td>
          </tr><tr>
            <td scope="row">showWarnings</td>
            <td>true</td>
            <td>boolean</td>
          </tr><tr>
            <td scope="row">useWizards</td>
            <td>true</td>
            <td>boolean</td>
          </tr><tr>
            <td scope="row">defaultMode</td>
            <td>none</td>
            <td>string (sql, js or py)</td>
</tr></tbody></table>
</div>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<div class="admon-title">
Note
</div>
<p>
          string values are case sensitive.
</p>
</div>

</div>

</div>

</div>

</div>
<div class="copyright-footer">

</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="group-replication.html">Prev</a></td>
<td width="20%" align="center"><a accesskey="u" href="">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="document-store.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 18 Group Replication</td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top">Chapter 20 Using MySQL as a Document Store</td>
</tr>
</table>
</div>
</body>
</html>
